home *** CD-ROM | disk | FTP | other *** search
/ Aminet 6 / Aminet 6 - June 1995.iso / Aminet / util / cli / GCd.lha / gcd / GCd.doc.eng < prev    next >
Encoding:
Text File  |  1994-12-16  |  16.0 KB  |  386 lines
  1. /************************************************************************/
  2. /**     Documentation about                                            **/
  3. /**                          GCd V2.3                                  **/
  4. /**                                                                    **/
  5. /**     a Shareware program              written by Giulio Ceriola     **/
  6. /**                                                                    **/
  7. /**                                  ( Version finished on 15-Dec-94 ) **/
  8. /************************************************************************/
  9.  
  10. This program was written by Giulio Ceriola and it is freely distributable
  11. with the only restriction of distribuite all the relative documentation;
  12. it consists of:
  13.  
  14.                 GCd                Executable file that can run on O.S.
  15.                                    2.x and superior (included 2.0). It
  16.                                    supports two language: italian and english
  17.                 GCD_1.3            Executable file compatible with the O.S
  18.                                    1.2 and 1.3 (see the readme)
  19.                 GCd.doc            Italian documentation about the program,
  20.                                    for each version.
  21.                 GCd.doc.eng        English documentation (this file)
  22.                 GCd_1.3.leggimi    Short italian readme for 1.2 and 1.3 users
  23.                 GCd_1.3.readme     As the precedent, but in english
  24.           libs20/reqtools.library  The required reqtools.library for SO 2.x
  25.                                    to be copied in the libs: directory if not
  26.                                    already present.
  27.           libs20/reqtools.library  As above, but for SO 1.x.
  28.              libs13/arp.library    The required arp.library for the version
  29.                                    for O.S. 1.x
  30.  
  31. Due to the time and the efforts spent to write this program, I decided to make
  32. Gcd a Shareware program. It means that, if you like this program and use it
  33. regularly, you has the moral duty to sent a contribute to the author (me).
  34. For any other inrfomation, pleas read the Shareware section of this file.
  35.  
  36. The idea of writing Gcd was born from the need of well manageing, through
  37. AmigaShell, the great number of directory that my system has, after the
  38. adding of an HD. It was necessary a command, "cd" like, that was able
  39. to find, and enter, a directory; giving it only a partial name independently
  40. from its path !
  41. The first hint was given me by a similar programm which tried to solve the
  42. same problem; it was DC written by Peter Struijk that I thanks. ;-)
  43.  
  44.  
  45. **********
  46. FEATURES *
  47. **********
  48.  
  49. GCd can enter a directory in four different ways.
  50. Tha first is the same of the Shell command cd; with same syntax and symbolism.
  51. The second is to enter a directory which is directly "visible" from the
  52. shell's actual directory, specificating a part of its name, too.
  53. For example, if the current directory is Ram: and here there are the
  54. T,ENV,TOOL,WORK directory; you can enter in one of them specifying only
  55. a part of their name (i.e.: 'to' let you to enter in TOOL, 'o' let you
  56. to choose to enter in wOrk or in ToOl; but if you specify 't' you
  57. will directly enter in T ("cd" mode)).
  58. The third way is to enter in ANY directory which is present in ALL the
  59. "fisical" device of the system, using only a part of its name.
  60. That's possible thanks the use of a file, that must be located in the
  61. s: directory (or in gcd:, if the user has assigned it), named Lista.gcd which
  62. contains all the complete path and names of the directory that the user want
  63. to be 'visible' from Gcd.
  64. This file is an ASCII file and can be edited with a normal text editor;
  65. but the program itself can efficently manage it.
  66. To refer to this file in the next chapter, I will use the expressions
  67. 'LIST' or the full name Lista.gcd.
  68. The last way is by file requester.
  69.  
  70.  
  71. ***********************
  72. LINE COMMAND's SYNTAX *
  73. ***********************
  74.  
  75. Gcd can be used only from Shell or CLI !
  76. Its syntax is:
  77.  
  78.             Gcd [argument] [options] [number]
  79.  
  80.  POSSIBLE USES
  81.  
  82. Gcd, as the command "cd", can be used in various manners:
  83.  
  84. - To Show a brief help                                          (1)
  85.   Syntax: Gcd ?
  86.  
  87. - To Show the actual directory                                  (2)
  88.   Syntax: Gcd
  89.  
  90. - To enter in the parent directory(ies) of the actual           (3)
  91.   Syntax: Gcd / (// ...)
  92.  
  93. - To enter in a directory which name is ENTIRELY specified      (4)
  94.   Syntax: Gcd <full path of the new directory>
  95.  
  96. - To enter a directory searching it in the stored 'LIST' and    (5)
  97.   between the "visible" ones                                     
  98.   Syntax: Gcd <partial name> [options] [number]
  99.  
  100. - To enter a directory and to search another between the        (5a)
  101.   "visible" ones, specifying, in the argument, the WHOLE path
  102.   of the first one (first level directory) and else a part of
  103.   the name of the second one
  104.   Syntax: Gcd <path.1st level + partial name>
  105.  
  106. - To enter a directory by choosing it with a file-requester.    (6)
  107.   The requester let the multi-selection, but only the first
  108.   selection will be considered.
  109.   Syntax: Gcd !
  110.  
  111. - Modify the stored file Lista.gcd                              (7)
  112.   Syntax: Gcd <device name> options
  113.   (options necessary !)
  114.  
  115.  
  116.   OPTIONS
  117.  
  118. All the options must be togheter and preceded from the symbol "-", and
  119. them must be put always after an argument.
  120. Them modify (or let) the precedent action numer (5) and (7).
  121.  
  122.  
  123. Option logically linked to the searching function  (5)
  124.  
  125.  Character option      Effect
  126.  
  127.       p            The searching between the path stored in Lista.gcd
  128.                    will not be done.
  129.       e            It asks the program of searching a directory whose
  130.                    name is EQUAL to the argument specified in the
  131.                    argument line (if present)
  132.       f            The program will choose always the first directory 
  133.                    found.
  134.  
  135.  
  136. Options logically linked to the functions of manageing the tile Lista.gcd
  137. (7) Whithout them the manageing function will not work
  138.  
  139.  Character options     Effect
  140.  
  141.       s            The program will delete the actual LIST and will create
  142.                    a new which contains all the path of the device specified
  143.                    as argument in the command line.
  144.       a            As the previous, but the LIST will not be deleted; and the
  145.                    path will be only added to it.
  146.       u            The program will update the LIST. All the old path of the
  147.                    device specified as argument will be first removed then
  148.                    the new ones will be added.
  149.       n            The program will not check if the argument specified is a
  150.                    "real" (ok) device or an "assigned" one (wrong).
  151.                    (really I never use that features, but someone could like
  152.                    it)
  153.       o            All the previous operations are done serching for the
  154.                    file Lista.gcd in the device Gcd:
  155.  
  156. P.S.
  157. When I write about a "real" devices, I refer to a "Fisical device".
  158. I often exchanng the word "directory" and "path", becouse I means the
  159. same thing: a directory with its full path.
  160.  
  161.  NUMBER
  162.  
  163. When a partial name is specified as 'argument' and the funtion (5) works
  164. successfully, you can choose directly which of the founded directory,
  165. will be entered, by specifying the correspondent number of the directory
  166. that you want (only between the directory present in the LIST).
  167. Where is the usefulness if you don't know or remember the right number ?
  168. You can always choose a number a bit inferior than the right one, so
  169. at the next search the program will start from it instead of the first one.
  170. For good understand that, please read the next chapter and so reread this
  171. passage.
  172.  
  173. **********************************
  174. WORKING OF THE VARIOUS FUNCTIONS *
  175. **********************************
  176.  
  177. About the function numbered (1) (2) (3) (4):
  178. the use and syntaz are exactly the same of the AmigaDOS Cd command's one.
  179.  
  180.  
  181. About the functions (5):
  182. The program, IN EACH CASE tries to execute the function (4), and ONLY if it
  183. fails, the program will do the searching.
  184. In this case, Gcd compare the 'argument' with all the NAME (without the path)
  185. of the stored directory in Lista.gcd.
  186.  
  187. At the end of the comparaison there are three possible case:
  188.  
  189. -Searching successfull ... only a path was found.
  190.  The program will show its name with the full path, and will enter it.
  191.  
  192. -Searching successfull ... more than one path found.
  193.  The program will enter one of the found directory.
  194.  In this case the program will store in a file in the ENV: directory, the
  195.  partial name specified as 'argument', the number of found path and
  196.  the number of the one actually selected (and entered).
  197.  For shifting between the various directory found, it is enough to repeat
  198.  the command with the SAME 'argument'; so the program will enter the next
  199.  directory found. When the last found directory is enter, the program will
  200.  re-start from the first one.
  201.  In each case, the program will show the name of the directory entered,
  202.  its number and the number of the all ones found.
  203.  If the ENV: device is not assigned, this last features will not work
  204.  (but the number option will yet work).
  205.  
  206. -Searching failed ... no path found.
  207. (or when the 'p' option is specified)
  208.  In this case the program will compare all the directory visible from
  209.  the actual one with the 'argument' specified. At the end of the
  210.  comparaison the program's behaviour will be similar the precedent:
  211.  
  212.      -Searching successfull ... only a path found.
  213.       The program will show tha path's name, and will enter it.
  214.  
  215.      -Searching successfull ... more than one path found.
  216.       The program will show the name of the first found and will wait a
  217.       key. If the <space bar> is pressed the program will show the next and
  218.       so on; otherwise the program will enter the actually showed path.
  219.  
  220.      -Searching failed ... no path found
  221.       An error message will be showed, stating 'directory not found' and
  222.       the program will end.
  223.  
  224.  
  225. About the function (5a)
  226. The program splits the arguments passed in the command line and gets the
  227. path of the first level directory (by finding the last modifier: the ':'
  228. or '/' characters). After that it enters this and, if all is right, makes
  229. its search between the "visible" paths and the program acts as described
  230. in (5).
  231. If the program can enter the first level directory it will be displayed
  232. the relative error message.
  233.  
  234.  
  235. About the function (7)
  236. The program creates/updates the small database LIST, inserting the paths of
  237. the selected device
  238. It must be noticed that this function will be activated ONLY IF the
  239. corresponding options 'a','u' or 's' are specified.
  240.  
  241.  
  242. For working corretly the program store some preferences in the s: directory
  243. in a file named "gcd.cfg". At now it is not modifyable from the user ...
  244. but the future versions will let it.
  245.  
  246. **************************
  247. RUN TIME ERRORS - ADVISE *
  248. **************************
  249.  
  250. The run time errors and relative behaviour of Gcd are the following:
  251.  
  252. - Failure ot all the (1-5) operation <-> Directory not found
  253. - Failure or problems in writing/reading the archive Lista.gcd
  254.   (not recoverable, unless all the Lista.gcd is rebuild)
  255. - Failure in reading/writing the file Gcd.ENV in th logic device ENV:
  256.   (the prg goes on, but is no more possible to manage (or choose) all
  257.    the directory found)
  258. - Failure in allocating the resources
  259.   (not recoverable)
  260. - Error in command line syntax
  261.   (the program not starts)
  262.  
  263. Not recoverable = the program shows the kind of the error and ends.
  264.  
  265. ATTENTION in using the 'n' options. It is not logically compatible with
  266. the filosofy of Gcd (becouse often it happens that the SAME path is stored
  267. under different device, so is repeated more times); but it was added to
  268. satisfy the more malizious users !
  269.  
  270. ****ATTENTION****
  271. Iff you want to "manually" (with an editor) edit the file Lista.gcd instead
  272. of doing it by Gcd, you MUST REMEMBER of ADDING AT THE END of the file,
  273. a 'LF' line feed (or another character, but LF is preferred by me) after
  274. the last path ... otherwise a GURU will visit you !!
  275.  
  276. ***************
  277. COMPATIBILITY *
  278. ***************
  279.  
  280. The GCd package includes two versions.
  281.  
  282. One of them is compatible with O.S. 2.0, 2.x and superior is localized
  283. and can use two language, italian and english. It not uses any catalogs,
  284. but open the locale for detecting the system language.
  285. It locale is not supported, the language selected is the english.
  286.  
  287. The other version is compatible with O.S. 1.2 and 1.3. The only language
  288. suported is the english one, but the italian can be forced by using the
  289. special option -i present only on this version.
  290.  
  291. GCd needs the reqtools.library (must be stored in the libs: directory)
  292. for performing the entering of a directory by requester (6).
  293. Also the 1.x version need the arp.library for manageing the wildcards.
  294.  
  295. *************************
  296. SHAREWARE's INFORMATION *
  297. *************************
  298.  
  299. Becouse the time and efforts spent for writing and testing this program
  300. I make GCd a shareware program. It means that if you like it and use it
  301. regularly it is your moral due to send me a contribute.
  302.  
  303. The not registeres program has now some limitation in working and no limit
  304. in using during time.
  305. The disabled feature are the choosing by requester and use of wildcards.
  306.  
  307. The requested contribute is 10000 Lit for users who lives in Italy or
  308. 9$ (USD) for all others (because of the different postal cost).
  309.  
  310. Possible way of payment:
  311.  
  312.         - Postal Money Order (it is the best for me)
  313.         - Cash
  314.  
  315. or other forms that you prefer, sending it to:
  316.  
  317.            Giulio Ceriola
  318.            v. C.Rosalba 38/a
  319.            70124 BARI ITALY
  320. if you are interested my phone number is (intern. prefix)-80-513311
  321.  
  322. You should write me a letter, too.
  323. You have to specify your full address, your system (incluse version of O.S.),
  324. if you use HD or not and if you can access to some E-mail net, please state
  325. it in the letter.
  326. After register, I will send you the last version of the program and a key.
  327.  
  328.  
  329. *****************
  330. HISTORY VERSION *
  331. *****************
  332.  
  333. 1.0     First version released
  334. 1.1     Changed the program structure
  335.         Corrected some small bug in recognaising the options
  336.         Speeded up the managing of the file Lista.gcd
  337.         Optimized the program's dimension (not released)
  338. 1.6     Modified the layout of the operation of choosing the path
  339.         between the ones found between the visible ones.
  340.         Now the -e option work correctly
  341.         Added the number feature.
  342.         Added the support of the LIST in the Gcd: device.
  343.         Added the possibilty of making the "search between visible paths"
  344.         starting from another directory (instead of the actual one).
  345. 2.0     Added the possibility of enter a directory by selecting it from
  346.         a requester; for that the program structure has been changed a lot.
  347.         The program will work only for 30 days.
  348.         Version for the 1.x O.S developed, too.
  349. 2.2     Added the use of wildcards in the 2.x version, only for registered
  350.         users.
  351.         Now the wildcards work in the 1.3 version of the program, too,
  352.         thanks to the Arp.library.
  353. 2.3     Changed the shareware's limitations. Now limits are about not use
  354.         of option ! and of wildcards.
  355.  
  356.  
  357. ****************************************
  358. FUTURE PLANNING - EXTERNAL SUGGESTIONS *
  359. ****************************************
  360.  
  361. For the next version I thik to abandon the 1.3 version; unless some
  362. registration for that version will arrive.
  363.  
  364. Now I am working on these new features:
  365.  
  366. - Option for excluding the searching using the Lista.gcd database.
  367. - Selecting a dir specifying some other "clues" other than entire path
  368. - Possibility of manageing the path found using Lista.gcd, in the same
  369.   manner of the other one, using a particolar option.
  370.  
  371. Every suggestion, critics or request is well accepted.
  372. To contact me you can write a letter at the addres above specified or via
  373. E-Mail at the following addresses:
  374.  
  375.               Fidonet   2:335/704.4@fidonet.org
  376.               Amiganet 39:102/602.4@amiganet.ftn
  377.               RPGNet   96:390/1.4@rpgnet.ftn
  378.               VNet     46:1390/11.4@vnet.ftn
  379.  
  380. o connecting to the BBS:
  381.  
  382.               Prometheus      tel. ++39-80-5515278
  383.                               on Modem USR HST 21600.
  384.  
  385. and sending a message to me (the Cosysop :-) ).
  386.